Cream of the Crop 25/Cream of the Crop 25.iso/os2/srefv12i.zip/dir.doc

Text File | 1997-03-17 | 10KB | 201 lines

     !DIR: SRE-Filter's built-in directory display facility for SRE-Filter

!DIR is SRE-Filter's built in directory display facility.

 * It's primary use is by the !CREATE option of AUTO_NAME; which instructs
   SRE-Filter to generate a directory listing "when there is no INDEX file".
 * !DIR can also be called explicitly as one of SRE-Filter's
   "special commands".
 * To improve performance, !DIR will "cache" directory listings;
   which it will use (after checking for changes).
 * For those interested in a more configurable directory display procedure,
   we recommend SRE-Filter's GETAFILE add-on.

By default, !DIR displays a "sorted by name" directory listing with a
descriptive icon, a filename (that links to the file), creation date,
and size.  You can change display options by modifying two SRE-Filter
parameters, DIR_EXCLUSION and DIR_OPTIONS.

1) DIR_EXCLUSION: a space delimited  list of 'files and subdirectories'
                    to exclude. Note that the * wildcard can be used.
      Example: dir_exclusion='HTACCESS.  DESCRIBE.TXT /PRIVATE  *.CNT '

2) DIR_OPTIONS: A space delimited list  of display options.
   The following lists the available options:

    AUTO_DESCRIBE == Try to create descriptions. This is done by extracting
                     <TITLE> and <META NAME="DESCRIPTION" Content="xx">
                     headers from HTML files,  the -z comments or
                     FILE_ID.DIZ files from .ZIP files, and the beginning of
                     plain text files.

    DESCRIBE=filename.ext == Use one line descriptions that are contained
                             in filename.ext. If just a DESCRIBE is included,
                             the filename.ext is assumed to be DESCRIBE.TXT
                             (see below for more details)

    DESC_LEN=nnn == Maximum characters to display in the description (ignored
                    if neither DESCRIBE or AUTO_DESCRIBE options are included)

    DATEFMT=x == The date format used; where x is one of B C D E M N O S U W.
             Where, given a date of 27 Aug 1988
                B:    725975
                D:    240
                E:    27/08/88
                L:    27 August 1988
                M:    August
                N:    27 Aug 1988
                O:    88/08/27
                S:    19880827
                U:    08/27/88
                W:    Saturday

           Note that if "x" is not one of these, N is used.


    HEADERFILE=filename.ext == A file to use as a "header".  If no
                               filename.ext is given, then DIR.HDR
                               is looked for. See below for details.
    FOOTERILE=filename.ext == A file to use as a "footer".  If no
                               filename.ext is given, then DIR.FTR
                               is looked for. See below for details.

    MULTI_SEND  == If the client's browser supports "Connection:Keep-Alive"
                   (i.e.; NetScape 1.3), and the directory contains more then
                   20 files, and AUTO_DESCRIBE will be attempted ..
                   then MULTI_SEND instructs  !DIR to display
                   "status" messages as the files are processed. These
                   status messages (written after every 15 files) are
                   sequentially displayed; and after all files have been
                   processed, they will be overwritten by the directory
                   listing.
                   Note that older browsers (WebEx) do not support "Connection:
                   Keep-Alive"; !DIR will detect this and not attempt to
                   send status messages to such browsers.

    NOCACHE == Do NOT use the !DIR cache (force recreation of the
               directory listing)

    NOSIZE ==  Suppress display of size.
    NOTIME ==  Suppress display of creation time
    NODATE ==  Suppress display of creation time and date
    NOICON ==  Suppress icon display
    NOSORT ==  Suppress sort-by-name
    NODIR  ==  Suppress subdirectory display (display files only)
    NO_RECURSE_DIR == Do NOT Use DIR on subsequent directories. Instead, use
                    a standard link to the directory.  Otherwise,
                    !DIR will traverse the directory tree (clicking
                    on a child directory will re-invoke !DIR).
    SHOWPARENT ==  Allow client to go up to parent. This CAN be used with
                   the NODIR option.
    SIZEFMT=aaaaa == The size format: aaaaa=ABBREV means 13K,
                                      aaaaa=0 means 13,012

    TABLE  == use an HTML TABLE to display (otherwise, use <PRE> formatting)
    TABLE_BORDER=nnn  == Size of border (if table used). If nnn=0, then no
                         border is shown.
    TIMEFMT=nn ==  The time format: nn=24 means use 13:01, nn=0 means  1:01p


  Examples:
     DIR_OPTIONS='notime describe no_recurse_dir datefmt=u nocache '
     DIR_OPTIONS='showparent table auto_describe desc_len=300 multi_send '

  In addition to the DIR_OPTIONS parameter, you can append options
  after the directory name (the directory name MUST immediately follow
  the ?.  Seperate each option with a space (or a + if you are hand
  coding a URL), and NOT with a &. The options are the same as above.
       For example:  /DIR?dir1+nosize+auto_describe

  Each of these options can be specified as is, or as option=0,
  which "turns them off".  This =0 form is useful if you wish
  to override a "parameter" settting with "request selector" option.
  Alternatively, option=1 "turns them on" (note that turning on a
  NOxxx option may mean suppressing a piece of the file info display).

Notes on the DESCRIBE option:

  * The description file (say, DESCRIBE.TXT) is assumed to be in the
    "own directory". Thus, seperate directories must have their "own"
    description file.

  * The DESCRIBE option expects a  "filename.ext" after an
    = sign. If you leave this off, DESCRIBE.TXT is used (if available).

  * The description file (i.e.; DESCRIBE.TXT) file should be organized as
      FILE1.xxx a description
      file2.yyy  another description
      /subdir1      a subdirectory description

  * Note that descriptions start with a file name (or a directory name,
    which must be preceded by a /) followed by the description
    (seperated from the filename by at least one space).

  * The description must be on one (arbitrarily long) line. However, it will
    be formatted to fit in the (possibly multi-line) display area.
    This is in contrast with several SRE-Filter add-ons, which permit
    multi-line descriptions.

  * When used with AUTO_DESCRIBE, if an explicit description is found
    in the description file, it is always used. That is, AUTO_DESCRIBE
    only applies to files that do NOT have an entry in the description file
    (assuming the DESCRIBE option is used).

  * If you want to suppress all descriptions (it's much faster when you
    don't display descriptions), set AUTO_DESCRIBE=0 and DESCRIBE=0.


Notes on caching

  * Caching is meant to be used in conjunction with the AUTO_DESCRIBE
    and DESCRIBE=filename option. If you are not including descriptions,
    then caching will probably not help a lot.

 *  A fairly simple caching algorithim is used, which will limit
    the cache's usefulness if !DIR is used extensively.
    If you intend to use !DIR extensively, you should consider
    using the BBS add-on.

  * Caching uses files that are stored in the TEMPDATA_DIR directory
    (typically, \GOSERVE\TEMP).  A _DIR.IDX file is used as a reference
    index, and _nnnnn.DSH files are used as "directory cache" files.

  * SRE-Filter will check the file-stamps of all files and subdirectories
    in the requested directory.  In addition, it will check the
    dir_option and dir_exclusion parameters.  If any of these have
    changed, the cache entry will not be used.
    Note: actually, a CRC of this information is used; thus, on very rare
          occasions SRE-Filter will NOT detect a change.

  * The DIR_CACHE_DURATION and DIR_CACHE_SIZE variables (set in SREFILTR.80)
    are used to set the size and lifespan of entries in the directory
    cache.  The default values are 3 days and 1Megabyte.
    Note that about once a day, !DIR will (when invoked) clean up
    the directory cache (say, get rid of entries that have somehow
    become orphaned).

  * To suppress, on a request specific basis, SRE-Filter's use of this
    cache; just include a NOCACHE option in the request selector (using the
    !DIR?dirname+NOCACHE syntax). To permanently suppress  it,
    set DIR_CACHE_SIZE=0

   * Cache entries are identified by both fully qualified directory,
     and by the "option list and exclusion" lists.
     Thus, multiple views of the same directory may be cached.

Notes on the HEADERFILE and FOOTERFILE options.

  * The header-file and footer-file is assumed to be in the "own" directory.
  * If a HEADERFILE is specified, and exists, the default
    header is NOT written.
  * If a HEADERFILE is specified, it MUST contain a <BODY>
    element. In all likelihood, that's why you'ld use it
    (so that you could specify a <BODY BACKGROUND=xxx.gif> element)!
  * The HEADERFILE option expects a  "filename.ext" after an
    = sign. If you leave this off, DIR.HDR is used (if available).
    Similarly, if no file exists after the FOOTERFILE, a DIR.FTR file
    is used (if available).


:End of DIR.DOC.